/*!
 * \file WtExecPorter.h
 * \project WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief 执行监控Porter接口定义
 * 
 * \details 本文件定义了WonderTrader执行监控模块的C语言接口，
 *          提供执行监控系统的初始化、配置、运行、日志记录、版本获取、
 *          释放资源和持仓设置等核心功能。
 *          
 *          主要功能包括：
 *          - 执行监控系统的生命周期管理
 *          - 配置文件加载和系统配置
 *          - 日志系统集成和消息记录
 *          - 版本信息查询
 *          - 持仓目标设置和管理
 *          
 *          该接口主要用于：
 *          - 跨语言调用（Python、C#等）
 *          - 第三方系统集成
 *          - 独立执行监控服务
 */
#pragma once
#include <stdint.h>
#include "../Includes/WTSMarcos.h"

typedef const char*			WtString;

#ifdef __cplusplus
extern "C"
{
#endif

	/*!
	 * \brief 初始化执行监控系统
	 * 
	 * \details 初始化执行监控系统的日志配置和基础环境。
	 *          该函数必须在其他所有函数之前调用。
	 *          支持从文件或字符串内容加载日志配置。
	 * 
	 * \param logCfg 日志配置文件路径或配置内容
	 * \param isFile 是否为文件路径，true表示文件路径，false表示配置内容
	 * 
	 * \note 该函数具有幂等性，重复调用不会产生副作用
	 * \see config_exec, run_exec
	 */
	EXPORT_FLAG	void		init_exec(WtString logCfg, bool isFile = true);

	/*!
	 * \brief 配置执行监控系统
	 * 
	 * \details 加载执行监控系统的配置文件，包括基础数据、
	 *          行情解析器、交易通道、执行器等配置信息。
	 *          如果配置文件路径为空，则使用默认配置文件"cfgexec.json"。
	 * 
	 * \param cfgfile 配置文件路径或配置内容
	 * \param isFile 是否为文件路径，true表示文件路径，false表示配置内容
	 * 
	 * \note 必须在init_exec之后、run_exec之前调用
	 * \see init_exec, run_exec
	 */
	EXPORT_FLAG	void		config_exec(WtString cfgfile, bool isFile = true);

	/*!
	 * \brief 运行执行监控系统
	 * 
	 * \details 启动执行监控系统的所有组件，包括行情解析器、
	 *          交易通道、执行器等。系统开始接收行情数据、
	 *          处理交易指令和执行监控逻辑。
	 * 
	 * \note 该函数会阻塞当前线程，直到系统停止运行
	 * \see init_exec, config_exec, release_exec
	 */
	EXPORT_FLAG	void		run_exec();

	/*!
	 * \brief 写入日志消息
	 * 
	 * \details 向执行监控系统的日志系统写入指定级别的日志消息。
	 *          支持按分类记录日志，便于日志管理和问题排查。
	 * 
	 * \param level 日志级别（参考WTSLogLevel枚举）
	 * \param message 日志消息内容
	 * \param catName 日志分类名称，空字符串表示使用默认分类
	 * 
	 * \note 日志级别包括：调试、信息、警告、错误等
	 * \see WTSLogLevel
	 */
	EXPORT_FLAG	void		write_log(unsigned int level, WtString message, WtString catName);

	/*!
	 * \brief 获取版本信息
	 * 
	 * \details 获取执行监控系统的版本信息字符串，
	 *          包括平台信息、版本号、编译日期和时间。
	 *          版本信息格式：[平台] [版本号] Build@[编译日期] [编译时间]
	 * 
	 * \return 版本信息字符串指针
	 * 
	 * \note 返回的字符串指针指向静态内存，无需释放
	 */
	EXPORT_FLAG	WtString	get_version();

	/*!
	 * \brief 释放执行监控系统资源
	 * 
	 * \details 停止执行监控系统的运行，释放所有分配的资源，
	 *          包括行情解析器、交易通道、执行器等组件。
	 *          该函数应在系统退出前调用。
	 * 
	 * \note 调用该函数后，系统将停止所有监控和执行活动
	 * \see init_exec, run_exec
	 */
	EXPORT_FLAG	void		release_exec();

	/*!
	 * \brief 设置持仓目标
	 * 
	 * \details 为指定合约设置目标持仓量，执行监控系统将根据
	 *          当前持仓和目标持仓的差异，自动执行相应的交易指令。
	 *          支持多空持仓，正数表示多头，负数表示空头，零表示平仓。
	 * 
	 * \param stdCode 标准合约代码（如：SHFE.rb2101）
	 * \param targetPos 目标持仓量，正数为多头，负数为空头，0为平仓
	 * 
	 * \note 执行器将根据配置的执行策略（如TWAP、最小冲击等）执行交易
	 * \see WtExecRunner::setPosition
	 */
	EXPORT_FLAG	void		set_position(WtString stdCode, double targetPos);

#ifdef __cplusplus
}
#endif